e2e/case/particleRenderer-limitVelocity.ts (1)

27-27: ⚠️ Potential issue | 🟡 Minor

Hook this case into the screenshot harness.

initScreenshot and updateForE2E are still unused, so the capture can happen before the texture load and first burst settle. Please call updateForE2E(engine, 500) and initScreenshot(engine, camera) after the particle setup completes, even if that means threading camera into createScalarLimitParticle().

Also applies to: 63-65, 68-145

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@e2e/case/particleRenderer-limitVelocity.ts` at line 27, After the particle
setup completes, hook the test into the screenshot harness by calling
updateForE2E(engine, 500) and then initScreenshot(engine, camera); if camera
isn't available where you build the particle case, thread the camera through
(e.g. add a camera parameter to createScalarLimitParticle or return the camera
from the setup) so you can call initScreenshot(engine, camera) immediately after
setup; apply the same change to the other similar cases referenced (the blocks
that import initScreenshot/updateForE2E).

packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts (2)

256-270: ⚠️ Potential issue | 🟠 Major

Treat randomized drag as a random-mode configuration.

_uploadDrag() supports TwoConstants and TwoCurves, but _isRandomMode() still only checks the limit curves. In separate-axes mode it also requires every axis to be randomized. The module-level random check should flip on whenever any limit axis or drag uses a randomized mode; otherwise the generator skips the per-particle random this shader path needs and drag becomes deterministic.

Also applies to: 429-448

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts` around
lines 256 - 270, The _isRandomMode() function currently only inspects
_limitX/_limitY/_limitZ modes (and requires all axes randomized when
_separateAxes is true), but it must also treat randomized drag as random-mode so
the per-particle random shader path is enabled; update _isRandomMode() to return
true if any of _limitX/_limitY/_limitZ is in ParticleCurveMode.TwoConstants or
TwoCurves OR if the drag configuration inspected by _uploadDrag() is in
TwoConstants/TwoCurves (and when _separateAxes is true, consider each axis ORed
rather than requiring all three), ensuring the method references the same drag
mode checks used by _uploadDrag() so randomized drag flips the random-mode flag;
apply the same fix to the other _isRandomMode() copy around the 429-448 area.

---

362-424: ⚠️ Potential issue | 🟠 Major

Don't silently fall back to constants for mixed per-axis modes.

Anything other than “all curves” or “all constants” drops into the constant upload branch. A setup like limitX = Curve, limitY = Constant, limitZ = TwoConstants loses the authored curve/random data instead of matching the per-axis configuration. Either reject mixed setups or upload each axis independently.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts` around
lines 362 - 424, In _uploadSeparateAxisLimits detect and handle each axis mode
individually instead of falling back to the “all curves” vs “all constants”
branches: inspect limitX.limitY.limitZ modes and for each axis upload the
appropriate data (for curves use _limit{X|Y|Z}MaxCurveProperty and
_limit{X|Y|Z}MinCurveProperty when TwoCurves, for constants use
_limitMaxConstVecProperty/_limitMinConstVecProperty but only set the
corresponding component), set modeMacro to reflect per-axis curve/constant usage
(or compute a composite shader macro logic) and set randomMacro only if any axis
is random (TwoCurves/TwoConstants) while preserving each axis’s authored values;
modify _uploadSeparateAxisLimits, the uses of
LimitVelocityOverLifetimeModule._limitXMaxCurveProperty/_limitXMinCurveProperty/_limitY.../_limitZ...
and the constant vector packing logic to write per-component values rather than
globally switching branches.

packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts (2)

256-265: ⚠️ Potential issue | 🟠 Major

_isRandomMode() doesn't account for drag's random modes.

The method only checks _limitX, _limitY, _limitZ modes but ignores _drag. When drag uses TwoConstants or TwoCurves while limits use non-random modes, the particle generator won't allocate per-particle random values for drag interpolation, causing all particles to use the same drag factor.

Suggested fix to include drag mode check

   _isRandomMode(): boolean {
+    const dragRandom = this._drag.mode === ParticleCurveMode.TwoConstants || 
+                       this._drag.mode === ParticleCurveMode.TwoCurves;
     if (this._separateAxes) {
       return (
         (this._limitX.mode === ParticleCurveMode.TwoConstants || this._limitX.mode === ParticleCurveMode.TwoCurves) &&
         (this._limitY.mode === ParticleCurveMode.TwoConstants || this._limitY.mode === ParticleCurveMode.TwoCurves) &&
         (this._limitZ.mode === ParticleCurveMode.TwoConstants || this._limitZ.mode === ParticleCurveMode.TwoCurves)
-      );
+      ) || dragRandom;
     }
-    return this._limitX.mode === ParticleCurveMode.TwoConstants || this._limitX.mode === ParticleCurveMode.TwoCurves;
+    return this._limitX.mode === ParticleCurveMode.TwoConstants || 
+           this._limitX.mode === ParticleCurveMode.TwoCurves || 
+           dragRandom;
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts` around
lines 256 - 265, The _isRandomMode() method currently checks only
_limitX/_limitY/_limitZ modes and misses _drag; update _isRandomMode in
LimitVelocityOverLifetimeModule to include a check that _drag.mode is also
TwoConstants or TwoCurves (when deciding random mode), i.e., when _separateAxes
is true require both all three limit axes and _drag be random-mode, and when
_separateAxes is false require either _limitX or _drag to be
TwoConstants/TwoCurves so per-particle random values are allocated for drag
interpolation.

---

356-421: ⚠️ Potential issue | 🟠 Major

Mixed per-axis modes silently fall back to constant upload.

When separateAxes is enabled with mixed modes (e.g., limitX = Curve, limitY = Constant, limitZ = Curve), lines 368-373 require all axes to be curves, so the code falls through to the constant path (line 402+). This silently discards curve data for axes configured with curves.

Consider either:

1. Supporting per-axis mode representation in the shader
2. Rejecting/warning on mixed-mode configurations
3. Documenting this as expected behavior

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts` around
lines 356 - 421, In _uploadSeparateAxisLimits detect mixed per-axis modes (using
limitX/limitY/limitZ and ParticleCurveMode) and avoid silently falling into the
constant branch: either (A) implement per-axis uploads by setting per-axis
curve/constant shader data (call shaderData.setFloatArray for curve axes using
limitX.curveMax/_curveMin and shaderData.setVector3 for constant axes) and
introduce per-axis mode macros (e.g., add/check new macros like
_limitXCurveMacro/_limitYCurveMacro/_limitZCurveMacro and still set
_limitIsRandomMacro where applicable), or (B) if you prefer not to support mixed
modes, throw/log a clear warning/error from _uploadSeparateAxisLimits when modes
differ instead of uploading constants only; update the function
_uploadSeparateAxisLimits, references to
LimitVelocityOverLifetimeModule._limitCurveModeMacro/_limitConstantModeMacro/_limitIsRandomMacro,
and the shaderData.setFloatArray/setVector3 calls accordingly so curve data is
not discarded silently.

e2e/case/particleRenderer-limitVelocity.ts (1)

136-147: Remove commented-out code.

Lines 136 and 143-146 contain commented-out alternative configurations. These should either be removed or, if they serve as documentation for alternative test scenarios, converted to separate test functions.

Suggested cleanup

   limitVelocityOverLifetime.limitZ = new ParticleCompositeCurve(0);
-  //   limitVelocityOverLifetime.limit = new ParticleCompositeCurve(1);
   limitVelocityOverLifetime.space = ParticleSimulationSpace.World;
   limitVelocityOverLifetime.dampen = 0.25;
   limitVelocityOverLifetime.drag = new ParticleCompositeCurve(0.0);
   limitVelocityOverLifetime.multiplyDragByParticleSize = true;
   limitVelocityOverLifetime.multiplyDragByParticleVelocity = true;
-
-  //   limitVelocityOverLifetime.enabled = true;
-  // limitVelocityOverLifetime.separateAxes = false;
-  // limitVelocityOverLifetime.limit = new ParticleCompositeCurve(0);
-  // limitVelocityOverLifetime.dampen = 1;
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@e2e/case/particleRenderer-limitVelocity.ts` around lines 136 - 147, Remove
the commented-out alternative configurations around the
limitVelocityOverLifetime block: delete the commented lines referencing
ParticleCompositeCurve, enabled, separateAxes, and dampen (the comments at and
around the limitVelocityOverLifetime assignment), or if those variants are
useful as documented alternatives, extract them into separate test functions
instead of leaving them commented; locate the limitVelocityOverLifetime usage
and ParticleCompositeCurve / ParticleSimulationSpace references in this file to
remove or refactor the commented alternatives accordingly.

packages/core/src/graphic/TransformFeedbackPrimitive.ts (2)

154-160: Consider reusing VertexBufferBinding objects to reduce allocations.

swap() creates a new VertexBufferBinding instance on every call. Since TF updates happen every frame for active particle systems, this causes per-frame allocations. Consider maintaining two pre-allocated binding objects and swapping between them.

Suggested optimization

+  private _renderBufferBindingA: VertexBufferBinding;
+  private _renderBufferBindingB: VertexBufferBinding;
+  private _useBindingA = true;

   resize(vertexCount: number): void {
     // ... existing code ...
     this._readBuffer = readBuffer;
     this._writeBuffer = writeBuffer;
-    this._renderBufferBinding = new VertexBufferBinding(this._readBuffer, this._byteStride);
+    this._renderBufferBindingA = new VertexBufferBinding(readBuffer, this._byteStride);
+    this._renderBufferBindingB = new VertexBufferBinding(writeBuffer, this._byteStride);
+    this._renderBufferBinding = this._renderBufferBindingA;
+    this._useBindingA = true;
     // ...
   }

   swap(): void {
     const temp = this._readBuffer;
     this._readBuffer = this._writeBuffer;
     this._writeBuffer = temp;
     this._currentVAO = this._currentVAO === this._vaoA ? this._vaoB : this._vaoA;
-    this._renderBufferBinding = new VertexBufferBinding(this._readBuffer, this._byteStride);
+    this._useBindingA = !this._useBindingA;
+    this._renderBufferBinding = this._useBindingA ? this._renderBufferBindingA : this._renderBufferBindingB;
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/graphic/TransformFeedbackPrimitive.ts` around lines 154 -
160, The swap() method in TransformFeedbackPrimitive currently allocates a new
VertexBufferBinding each call (this._renderBufferBinding = new
VertexBufferBinding(...)); instead, pre-allocate two VertexBufferBinding
instances (e.g., this._bindingA / this._bindingB) as members alongside
_vaoA/_vaoB and initialize them for the corresponding buffers and _byteStride,
then in swap() simply toggle which binding is active (assign
this._renderBufferBinding = this._bindingA or this._bindingB) and update their
internal buffer reference/stride if necessary; update any initialization code
that creates _renderBufferBinding to use the pre-allocated pair and ensure
_renderBufferBinding is swapped when _readBuffer/_writeBuffer and _currentVAO
are swapped.

---

61-86: Consider resetting _currentVAO reference in resize() to avoid stale reference.

After resize() sets _vaoDirty = true, the old VAOs will be deleted in rebuildVAOsIfNeeded(). However, if bindVAO() were called before rebuildVAOsIfNeeded(), _currentVAO would reference a deleted VAO. While the current usage pattern appears safe (rebuild is always called before bind), explicitly nullifying _currentVAO in resize() would make the code more defensive.

Suggested defensive fix

     this._vertexCount = vertexCount;
     this._initialized = true;
     this._vaoDirty = true;
+    this._currentVAO = null;
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/graphic/TransformFeedbackPrimitive.ts` around lines 61 -
86, The resize() method should clear the cached VAO reference to avoid holding a
pointer to a VAO that will be destroyed; add a line to set this._currentVAO =
null (or undefined consistent with class) when resizing—ideally right after
setting this._vaoDirty = true—so that rebuildVAOsIfNeeded() can safely recreate
VAOs and bindVAO() cannot reference a deleted object.

packages/core/src/particle/ParticleTransformFeedbackSimulator.ts (2)

127-127: Replace magic number with GL constant for clarity.

POINTS = 0x0000 is the raw WebGL constant value. Consider using gl.POINTS for better readability and maintainability.

Suggested fix

+    const gl = this._engine._hardwareRenderer.gl;
     // Bind VAO and execute TF for alive particles
     this._primitive.bindVAO();

-    const POINTS = 0x0000;
     if (firstActive < firstFree) {
-      this._primitive.draw(rhi, POINTS, firstActive, firstFree - firstActive);
+      this._primitive.draw(rhi, gl.POINTS, firstActive, firstFree - firstActive);
     } else {
-      this._primitive.draw(rhi, POINTS, firstActive, particleCount - firstActive);
+      this._primitive.draw(rhi, gl.POINTS, firstActive, particleCount - firstActive);
       if (firstFree > 0) {
-        this._primitive.draw(rhi, 0, firstFree);
+        this._primitive.draw(rhi, gl.POINTS, 0, firstFree);
       }
     }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/ParticleTransformFeedbackSimulator.ts` at line
127, Replace the magic numeric literal used for POINTS with the WebGL constant
from the existing GL context: change the declaration that sets POINTS = 0x0000
to use the in-scope WebGLRenderingContext constant (e.g., POINTS = gl.POINTS or
this.gl.POINTS depending on how the context is referenced in
ParticleTransformFeedbackSimulator) so the code uses the named constant instead
of the raw hex value.

---

109-113: Per-frame VertexBufferBinding allocation in update loop.

VertexBufferBinding is instantiated on every update() call (line 110). Since this runs every frame for active particle systems, it creates unnecessary GC pressure. Consider caching and reusing the binding when the instance buffer hasn't changed.

Suggested optimization

+  private _cachedInstanceBuffer: Buffer;
+  private _cachedInstanceBinding: VertexBufferBinding;

   update(
     instanceBuffer: Buffer,
     // ...
   ): void {
     // ...
-    const instanceBinding = new VertexBufferBinding(instanceBuffer, ParticleBufferUtils.instanceVertexStride);
+    if (this._cachedInstanceBuffer !== instanceBuffer) {
+      this._cachedInstanceBuffer = instanceBuffer;
+      this._cachedInstanceBinding = new VertexBufferBinding(instanceBuffer, ParticleBufferUtils.instanceVertexStride);
+    }
+    const instanceBinding = this._cachedInstanceBinding;
     this._primitive.rebuildVAOsIfNeeded(this._tfProgram, ParticleTransformFeedbackSimulator._tfElements, [
       { binding: instanceBinding, elements: ParticleTransformFeedbackSimulator._instanceElements }
     ]);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/ParticleTransformFeedbackSimulator.ts` around
lines 109 - 113, The code currently allocates a new VertexBufferBinding each
frame inside update(), causing GC churn; cache and reuse the binding instead:
add a class field (e.g., this._instanceBinding) and in update() only create a
new VertexBufferBinding when the instanceBuffer reference changes (compare
instanceBuffer to the cached binding's buffer or null), otherwise reuse the
cached binding when calling this._primitive.rebuildVAOsIfNeeded(this._tfProgram,
ParticleTransformFeedbackSimulator._tfElements, [{ binding:
this._instanceBinding, elements:
ParticleTransformFeedbackSimulator._instanceElements }]); ensure the cache is
cleared/updated whenever the instanceBuffer is replaced or disposed.

packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts (1)

44-44: Inconsistent shader property naming.

_dragConstantProperty uses "u_DragConstant" while all other properties in this module use the "renderer_LVL*" prefix (e.g., renderer_LVLDampen, renderer_LVLDragMaxCurve). Consider renaming to "renderer_LVLDragConstant" for consistency.

Suggested fix

-  static readonly _dragConstantProperty = ShaderProperty.getByName("u_DragConstant");
+  static readonly _dragConstantProperty = ShaderProperty.getByName("renderer_LVLDragConstant");

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts` at
line 44, Update the shader property name for consistency: change the string
passed to ShaderProperty.getByName in the static member _dragConstantProperty
from "u_DragConstant" to "renderer_LVLDragConstant" and ensure any other usages
that reference the shader property by name align with this new identifier (look
for references to _dragConstantProperty and any direct "u_DragConstant" usages
to update them).

packages/rhi-webgl/src/GLTransformFeedbackPrimitive.ts (1)

27-35: ⚠️ Potential issue | 🟠 Major

Rebuild VAOs when buffer bindings change, not only when program changes.

Line 27 currently keys cache on program.id only. If readBinding, writeBinding, or inputBinding points to a new buffer with the same program, VAOs keep stale bindings.

Suggested fix

 export class GLTransformFeedbackPrimitive implements IPlatformTransformFeedbackPrimitive {
   private _gl: WebGL2RenderingContext;
   private _vaoA: WebGLVertexArrayObject;
   private _vaoB: WebGLVertexArrayObject;
   private _lastProgramId = -1;
+  private _lastReadBuffer: unknown = null;
+  private _lastWriteBuffer: unknown = null;
+  private _lastInputBuffer: unknown = null;
@@
   updateVertexLayout(
     program: any,
     readBinding: VertexBufferBinding,
     writeBinding: VertexBufferBinding,
@@
   ): void {
-    if (program.id === this._lastProgramId) return;
+    const readBuffer = readBinding?.buffer;
+    const writeBuffer = writeBinding?.buffer;
+    const inputBuffer = inputBinding?.buffer;
+    if (
+      program.id === this._lastProgramId &&
+      readBuffer === this._lastReadBuffer &&
+      writeBuffer === this._lastWriteBuffer &&
+      inputBuffer === this._lastInputBuffer
+    ) {
+      return;
+    }
@@
     this._vaoA = this._createVAO(attribs, readBinding, feedbackElements, inputBinding, inputElements);
     this._vaoB = this._createVAO(attribs, writeBinding, feedbackElements, inputBinding, inputElements);
     this._lastProgramId = program.id;
+    this._lastReadBuffer = readBuffer;
+    this._lastWriteBuffer = writeBuffer;
+    this._lastInputBuffer = inputBuffer;
@@
   private _deleteVAOs(): void {
@@
     this._lastProgramId = -1;
+    this._lastReadBuffer = null;
+    this._lastWriteBuffer = null;
+    this._lastInputBuffer = null;
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/rhi-webgl/src/GLTransformFeedbackPrimitive.ts` around lines 27 - 35,
The code only rebuilds VAOs when program.id changes (checked via
this._lastProgramId), so VAOs stay stale if readBinding, writeBinding, or
inputBinding change; update the logic to also detect binding changes by tracking
unique identifiers for readBinding, writeBinding and inputBinding (e.g., buffer
id or a composite key) and include them in the cache check before returning, and
when any of those ids differ call this._deleteVAOs() and recreate
this._vaoA/this._vaoB via this._createVAO(attribs, ...), then update the stored
last-program and last-binding ids (e.g., this._lastReadBindingId,
this._lastWriteBindingId, this._lastInputBindingId) alongside
this._lastProgramId.

packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts (1)

260-269: ⚠️ Potential issue | 🟠 Major

Include drag random modes in module random-mode detection.

Line 260-Line 269 currently ignores drag random modes. This can skip per-particle random generation when drag is TwoConstants/TwoCurves but limits are non-random.

Suggested fix

   _isRandomMode(): boolean {
+    const dragRandom =
+      this._drag.mode === ParticleCurveMode.TwoConstants || this._drag.mode === ParticleCurveMode.TwoCurves;
+
+    const limitRandom = this._separateAxes
+      ? (this._limitX.mode === ParticleCurveMode.TwoConstants || this._limitX.mode === ParticleCurveMode.TwoCurves) &&
+        (this._limitY.mode === ParticleCurveMode.TwoConstants || this._limitY.mode === ParticleCurveMode.TwoCurves) &&
+        (this._limitZ.mode === ParticleCurveMode.TwoConstants || this._limitZ.mode === ParticleCurveMode.TwoCurves)
+      : this._limitX.mode === ParticleCurveMode.TwoConstants || this._limitX.mode === ParticleCurveMode.TwoCurves;
+
-    if (this._separateAxes) {
-      return (
-        (this._limitX.mode === ParticleCurveMode.TwoConstants || this._limitX.mode === ParticleCurveMode.TwoCurves) &&
-        (this._limitY.mode === ParticleCurveMode.TwoConstants || this._limitY.mode === ParticleCurveMode.TwoCurves) &&
-        (this._limitZ.mode === ParticleCurveMode.TwoConstants || this._limitZ.mode === ParticleCurveMode.TwoCurves)
-      );
-    }
-    return this._limitX.mode === ParticleCurveMode.TwoConstants || this._limitX.mode === ParticleCurveMode.TwoCurves;
+    return limitRandom || dragRandom;
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/modules/LimitVelocityOverLifetimeModule.ts` around
lines 260 - 269, The _isRandomMode method currently only checks limit curves and
ignores drag random modes; update it to also consider drag being in random modes
(ParticleCurveMode.TwoConstants or ParticleCurveMode.TwoCurves). Specifically,
in the branch where this._separateAxes is true, include checks for
this._dragX.mode, this._dragY.mode and this._dragZ.mode (alongside
_limitX/_limitY/_limitZ) and in the non-separate branch include this._drag.mode
in the OR logic with this._limitX.mode so that any drag TwoConstants/TwoCurves
causes _isRandomMode to return true.

packages/rhi-webgl/src/GLTransformFeedback.ts (1)

13-17: ⚠️ Potential issue | 🔴 Critical

Add explicit WebGL2 and handle-creation guards in constructor.

This constructor still assumes WebGL2 and does not check createTransformFeedback() result, which can fail and produce invalid state.

Suggested patch

  constructor(rhi: WebGLGraphicDevice) {
+    if (!rhi.isWebGL2) {
+      throw new Error("Transform Feedback requires a WebGL2 context.");
+    }
     const gl = <WebGL2RenderingContext>rhi.gl;
     this._gl = gl;
-    this._glTransformFeedback = gl.createTransformFeedback();
+    const tf = gl.createTransformFeedback();
+    if (!tf) {
+      throw new Error("Failed to create WebGLTransformFeedback.");
+    }
+    this._glTransformFeedback = tf;
   }

#!/bin/bash
set -e
# Confirm guard presence and constructor call paths
sed -n '1,120p' packages/rhi-webgl/src/GLTransformFeedback.ts
rg -nP --type=ts 'new GLTransformFeedback\s*\(' packages
rg -nP --type=ts -C3 'createPlatformTransformFeedback|isWebGL2' packages/rhi-webgl/src

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/rhi-webgl/src/GLTransformFeedback.ts` around lines 13 - 17, The
GLTransformFeedback constructor assumes WebGL2 and doesn't validate
createTransformFeedback() output; update the constructor in class
GLTransformFeedback to assert/guard that rhi.gl is a WebGL2RenderingContext (use
isWebGL2 or instanceof WebGL2RenderingContext) and check the result of
gl.createTransformFeedback(); if it returns null handle it by throwing or
returning a clear error (or set a safe fallback and log) and ensure
_glTransformFeedback is only assigned when non-null, referencing the
constructor, WebGL2RenderingContext, createTransformFeedback, and
_glTransformFeedback symbols.

e2e/case/particleRenderer-limitVelocity.ts (1)

27-28: ⚠️ Potential issue | 🟡 Minor

Wire the screenshot harness in this case setup.

initScreenshot/updateForE2E are imported but unused; the case never explicitly settles before capture. This can make snapshots timing-sensitive.

Suggested patch

-    .then((texture) => {
-      createScalarLimitParticle(engine, rootEntity, <Texture2D>texture);
+    .then((texture) => {
+      createScalarLimitParticle(engine, rootEntity, camera, <Texture2D>texture);
     });
 });
 
-function createScalarLimitParticle(engine: Engine, rootEntity: Entity, texture: Texture2D): void {
+function createScalarLimitParticle(engine: Engine, rootEntity: Entity, camera: Camera, texture: Texture2D): void {
@@
   limitVelocityOverLifetime.drag = new ParticleCompositeCurve(0.0);
   limitVelocityOverLifetime.multiplyDragByParticleSize = true;
   limitVelocityOverLifetime.multiplyDragByParticleVelocity = true;
+
+  updateForE2E(engine, 500);
+  initScreenshot(engine, camera);
 }

Also applies to: 64-68, 148-148

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@e2e/case/particleRenderer-limitVelocity.ts` around lines 27 - 28, The test
imports initScreenshot and updateForE2E but never uses them, so wire the
screenshot harness into the case: call initScreenshot() near the start of the
test setup to initialize the harness and, after any actions that change state
but before taking a snapshot, call await updateForE2E() to let the scene settle;
update the particleRenderer-limitVelocity test case (references to
initScreenshot and updateForE2E in the file) to include these calls in the setup
and immediately before captures so snapshots are not timing-sensitive.

packages/core/src/particle/ParticleTransformFeedbackSimulator.ts (1)

84-84: Avoid per-frame VertexBufferBinding allocation in hot update loop.

Line 84 allocates every frame. Reusing a cached binding (or mutating an existing one) will reduce GC churn during particle-heavy scenes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/ParticleTransformFeedbackSimulator.ts` at line 84,
The per-frame allocation of a VertexBufferBinding (variable instanceBinding)
inside ParticleTransformFeedbackSimulator causes GC churn; cache a reusable
binding on the simulator instance instead of constructing it each update: add a
class field (e.g., this.instanceBinding) created once using instanceBuffer and
ParticleBufferUtils.instanceVertexStride and reuse it every frame, updating its
buffer reference only if instanceBuffer changes (or mutate the existing binding)
so you stop allocating a new VertexBufferBinding each frame.

packages/core/src/shader/ShaderPass.ts (1)

153-163: Consider centralizing capability macro collection.

_getShaderLabProgram() rebuilds the same renderer-capability macro list that the non-ShaderLab path already needs. Pulling that into a shared helper would reduce drift if new capability macros get added later.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/shader/ShaderPass.ts` around lines 153 - 163, The code in
_getShaderLabProgram rebuilds renderer capability macros (e.g.,
GRAPHICS_API_WEBGL2/1, HAS_TEX_LOD, HAS_DERIVATIVES) into shaderMacroList;
extract that logic into a shared helper (for example a new private function like
collectRendererCapabilityMacros(engine: Engine, target: ShaderMacro[])) and call
it from _getShaderLabProgram and the non-ShaderLab path so both use the same
single source of truth; ensure the helper uses engine._hardwareRenderer and
ShaderMacro.getByName to push the same macros and update callers to remove the
duplicated push logic.

packages/core/src/particle/ParticleGenerator.ts (2)

979-1001: ⚠️ Potential issue | 🟠 Major

Rotate initial TF velocity for world simulation.

In world mode, Line 991-992 rotates/emits position in world space, but Line 998-1000 still uses local direction. This produces incorrect initial motion when emitter rotation is non-identity.

Suggested patch

   private _addFeedbackParticle(
     index: number,
     shapePosition: Vector3,
     direction: Vector3,
     startSpeed: number,
     transform: Transform
   ): void {
     let position: Vector3;
+    let velocity: Vector3 = direction;
     if (this.main.simulationSpace === ParticleSimulationSpace.Local) {
       position = shapePosition;
     } else {
       position = ParticleGenerator._tempVector32;
       Vector3.transformByQuat(shapePosition, transform.worldRotationQuaternion, position);
       position.add(transform.worldPosition);
+      velocity = ParticleGenerator._tempVector31;
+      Vector3.transformByQuat(direction, transform.worldRotationQuaternion, velocity);
     }
 
     this._feedbackSimulator.writeParticleData(
       index,
       position,
-      direction.x * startSpeed,
-      direction.y * startSpeed,
-      direction.z * startSpeed
+      velocity.x * startSpeed,
+      velocity.y * startSpeed,
+      velocity.z * startSpeed
     );
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/ParticleGenerator.ts` around lines 979 - 1001, The
feedback particle's initial velocity isn't rotated into world space in
ParticleGenerator._addFeedbackParticle when this.main.simulationSpace !==
ParticleSimulationSpace.Local; keep the existing world-space position transform
but also rotate the local direction by transform.worldRotationQuaternion (e.g.,
into a temporary Vector3) and use that rotated direction's x/y/z multiplied by
startSpeed in the call to this._feedbackSimulator.writeParticleData so emitted
velocities respect emitter rotation.

---

614-628: ⚠️ Potential issue | 🟠 Major

Backfill alive particles when enabling TF at runtime.

Line 621 only resizes TF buffers. Existing alive slots are not copied into TF state, so the first TF step can read default position/velocity for already-active particles.

Suggested patch sketch

   _setTransformFeedback(enabled: boolean): void {
     this._useTransformFeedback = enabled;
 
     if (enabled) {
       if (!this._feedbackSimulator) {
         this._feedbackSimulator = new ParticleTransformFeedbackSimulator(this._renderer.engine);
       }
       this._feedbackSimulator.resize(this._currentParticleCount, this._instanceVertexBufferBinding);
+      this._syncAliveParticlesToFeedback();
       this._renderer.shaderData.enableMacro(ParticleGenerator._transformFeedbackMacro);
     } else {
       this._renderer.shaderData.disableMacro(ParticleGenerator._transformFeedbackMacro);
     }
 
     this._reorganizeGeometryBuffers();
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/ParticleGenerator.ts` around lines 614 - 628, When
enabling transform-feedback in _setTransformFeedback, after creating/resizing
this._feedbackSimulator call a method to initialize/copy the current alive
particle state from the instance vertex data into the TF buffers so the first TF
step doesn't read default values; use this._instanceVertexBufferBinding and
this._currentParticleCount as the source and add/invoke a method on
ParticleTransformFeedbackSimulator (e.g. initializeFromInstanceBinding or
copyFromInstanceBuffers) to transfer per-particle attributes before enabling the
macro and before calling _reorganizeGeometryBuffers().

packages/core/src/particle/ParticleTransformFeedbackSimulator.ts (1)

84-104: ⚠️ Potential issue | 🟠 Major

Guard TF state cleanup with try/finally.

Line 85 enters TF update, but if any draw on Line 95/Line 97/Line 99 throws, Line 103 is skipped and TF state is left unclosed.

Suggested patch

     if (
       !this._simulator.beginUpdate(
         shaderData,
         ParticleBufferUtils.feedbackVertexElements,
         this._instanceBinding,
         ParticleBufferUtils.feedbackInstanceElements
       )
     )
       return;
 
-    if (firstActive < firstFree) {
-      this._simulator.draw(MeshTopology.Points, firstActive, firstFree - firstActive);
-    } else {
-      this._simulator.draw(MeshTopology.Points, firstActive, particleCount - firstActive);
-      if (firstFree > 0) {
-        this._simulator.draw(MeshTopology.Points, 0, firstFree);
+    try {
+      if (firstActive < firstFree) {
+        this._simulator.draw(MeshTopology.Points, firstActive, firstFree - firstActive);
+      } else {
+        this._simulator.draw(MeshTopology.Points, firstActive, particleCount - firstActive);
+        if (firstFree > 0) {
+          this._simulator.draw(MeshTopology.Points, 0, firstFree);
+        }
       }
+    } finally {
+      this._simulator.endUpdate();
     }
-
-    this._simulator.endUpdate();

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/ParticleTransformFeedbackSimulator.ts` around
lines 84 - 104, The TF (transform feedback) update calls into this._simulator
beginUpdate/draw/endUpdate must be wrapped so endUpdate always runs even if a
draw throws: capture the boolean result of this._simulator.beginUpdate(...) into
a local (e.g., began), and if began then execute the draw logic inside a try
block and call this._simulator.endUpdate() in a finally block; do not call
endUpdate when beginUpdate returned false. Update the code around
_simulator.beginUpdate / _simulator.draw / _simulator.endUpdate to use this
try/finally pattern so TF state is always cleaned up.

packages/core/src/particle/ParticleTransformFeedbackSimulator.ts (1)

84-104: ⚠️ Potential issue | 🟠 Major

Make TF update exception-safe with try/finally.

If any draw() call throws after beginUpdate() succeeds, endUpdate() is skipped. This leaves GL state corrupted (rasterizer discard enabled, transform feedback bound), which would break subsequent rendering.

Suggested fix

     if (
       !this._simulator.beginUpdate(
         shaderData,
         ParticleBufferUtils.feedbackVertexElements,
         this._instanceBinding,
         ParticleBufferUtils.feedbackInstanceElements
       )
     )
       return;
 
-    if (firstActive < firstFree) {
-      this._simulator.draw(MeshTopology.Points, firstActive, firstFree - firstActive);
-    } else {
-      this._simulator.draw(MeshTopology.Points, firstActive, particleCount - firstActive);
-      if (firstFree > 0) {
-        this._simulator.draw(MeshTopology.Points, 0, firstFree);
+    try {
+      if (firstActive < firstFree) {
+        this._simulator.draw(MeshTopology.Points, firstActive, firstFree - firstActive);
+      } else {
+        this._simulator.draw(MeshTopology.Points, firstActive, particleCount - firstActive);
+        if (firstFree > 0) {
+          this._simulator.draw(MeshTopology.Points, 0, firstFree);
+        }
       }
+    } finally {
+      this._simulator.endUpdate();
     }
-
-    this._simulator.endUpdate();

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/ParticleTransformFeedbackSimulator.ts` around
lines 84 - 104, The code calls this._simulator.beginUpdate(...), then performs
one or more this._simulator.draw(...) calls and finally
this._simulator.endUpdate(); make the update exception-safe by wrapping the draw
logic in a try/finally so that this._simulator.endUpdate() is always invoked
even if any draw() throws; locate the beginUpdate / draw / endUpdate calls in
ParticleTransformFeedbackSimulator and move the draw branches into the try block
with endUpdate() in the finally block to guarantee GL state is cleaned up.

packages/core/src/particle/ParticleGenerator.ts (1)

978-1001: ⚠️ Potential issue | 🟠 Major

Rotate initial TF velocity in world simulation mode.

Position is correctly transformed to world space (Lines 989-991), but velocity still uses local-space direction. This causes incorrect initial motion when the emitter has non-identity rotation.

Suggested fix

   private _addFeedbackParticle(
     index: number,
     shapePosition: Vector3,
     direction: Vector3,
     startSpeed: number,
     transform: Transform
   ): void {
     let position: Vector3;
+    let velocity = direction;
     if (this.main.simulationSpace === ParticleSimulationSpace.Local) {
       position = shapePosition;
     } else {
       position = ParticleGenerator._tempVector32;
       Vector3.transformByQuat(shapePosition, transform.worldRotationQuaternion, position);
       position.add(transform.worldPosition);
+      velocity = ParticleGenerator._tempVector31;
+      Vector3.transformByQuat(direction, transform.worldRotationQuaternion, velocity);
     }
 
     this._feedbackSimulator.writeParticleData(
       index,
       position,
-      direction.x * startSpeed,
-      direction.y * startSpeed,
-      direction.z * startSpeed
+      velocity.x * startSpeed,
+      velocity.y * startSpeed,
+      velocity.z * startSpeed
     );
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/particle/ParticleGenerator.ts` around lines 978 - 1001, The
initial velocity isn't rotated into world space in
ParticleGenerator._addFeedbackParticle when this.main.simulationSpace !==
ParticleSimulationSpace.Local; rotate the local-space direction by
transform.worldRotationQuaternion before scaling by startSpeed and passing
components to this._feedbackSimulator.writeParticleData. Use a temp vector
(don't overwrite shapePosition temp used for position—e.g., a dedicated temp
like ParticleGenerator._tempVector33 or a new local Vector3), call
Vector3.transformByQuat(direction, transform.worldRotationQuaternion,
rotatedDir), multiply rotatedDir by startSpeed, then pass rotatedDir.x/y/z to
writeParticleData instead of direction.x/y/z.

packages/core/src/Transform.ts (1)

54-54: Verify intentional removal of @ignoreClone from _parentTransformCache.

The @ignoreClone decorator was removed from _parentTransformCache. While _isParentDirty (line 53) is still @ignoreClone and defaults to true, ensuring the cache is recalculated on first access, the removal allows the cached parent reference to be processed during cloning.

Since Transform extends Component and has _remap, the reference should be correctly remapped if the parent is within the cloned subtree. However, this adds unnecessary cloning work since _isParentDirty = true will force recalculation anyway.

Consider keeping @ignoreClone on _parentTransformCache to avoid unnecessary remapping overhead:

+ `@ignoreClone`
  private _parentTransformCache: Transform = null;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/Transform.ts` at line 54, The _parentTransformCache field
lost its `@ignoreClone` decorator allowing it to be processed during cloning and
causing unnecessary remap work even though _isParentDirty (still `@ignoreClone`)
will force recompute; restore the `@ignoreClone` decorator on the
_parentTransformCache property in the Transform class so the cached reference is
skipped by the clone machinery (keeping _isParentDirty true ensures
recalculation) and mention/verify that _remap on Component still correctly
handles cases where the parent is inside the cloned subtree.